Software Vault: The Gold Collection/Software Vault - The Gold Collection (American Databankers) (1993).ISO/cdr46/multi_c1.zip/MULTI_C.DOC

Text File | 1992-11-08 | 59KB | 2,311 lines

                                MULTI-APP V1.0.1
                         ==============================

                         ______________________________

                         ==============================

                             Documentation Rev 0.3
                         Copyright 1992 by Jeff Heaton







                                 MULTI-APP V1.0
                             A MicroGenesis Product
                         Copyright 1992 by Jeff Heaton
                              All Rights Reserved

                             MicroGenesis Software
                               P.O. Box No 25534
                              St. Louis, MO 63125

                             VOICE: [phone]
                      DATA:[phone] n,8,1,1200-9600






































    Part I: The Multi-APP Core

    Introduction

     The MULTI-APP core is the heart of the MULTI-APP system.  All classes
    in the MULTI-APP system are derived from these "core classes." The
    primary purpose of this core is to give all MULTI-APP classes a
    consistent interface.  Many abstract classes(who
    se sole purpose is to define future classes) are defined here, as well
    as real classes for file and data handling.

     Using the MULTI-APP core you can provide your application with
    platform-independent access to the basic system resources that all
    applications need.  These are the file system, the serial ports, and
    basic data structure handling.  In addition a spec
    ial "error free" compression based communications protocol is provided
    to allow you to access other MULTI-APP applications and share
    information remotely.

     In addition to providing these basic services, MULTI-APP core allows
    you to use the MULTI-APP user interface package to produce GUI(graphic
    user interface) applications in a platform-independent manner.

    MultiApp Core Features:

     I. Platform Independent Access to Files:
      A. DEVICE compatible for I/O redirection
      B. Allows concurrent shared access of files
      C. Buffered character access provides maximum speed
      D. Fast block read/write functions for record handling
     II. Platform Independent Access to Serial Ports:
      A. DEVICE compatible for I/O redirection
      B. Optional Compression/Error correction(in SOFTWARE)
      C. Access to all hardware lines provided by host computer
     III. Misc Platform Independent Services:
      A. Integer stacks
      B. Base classes for linked lists
      C. File Maintenance functions


    License

     The MultiApp system is currently being marketed as ShareWare.
    Shareware is a unique software distribution method where you, the
    software user, gets to try out the program BEFORE you pay for it.  This
    is a FULL version of the MultiApp core, and you
    get a FULL copy of the text representation of the user manual to
    evaluate for a time period of 30(thirty) days.  If you wish to continue
    using MultiApp after this trial period, or if you publicly release a
    program(commercial,shareware, public domain
    or any other non-personal use) you MUST register your copy.  Upon
    registration you will receive the complete source code to the MultiApp
    product that you registered.  The source code, however, will be for
    your exclusive use and may not be distributed
     directly.  However, applications can be created using source code
    modifications.










     If you use MultiApp beyond the initial 30 day limit, or publicly
    release any application that contains MultiApp code you MUST have
    registered MultiApp.  To do otherwise is a direct violation of the
    MultiApp copyright.  However once you have register
    ed a MultiApp product you may use it in your own application, royalty
    free, for as many applications as you wish.

     The following information is not in classes and provide miscellaneous
    utility to the MULTI-APP system.  Some of the data structures defined
    here are only used in the MULTI-APP user interface and are thus only
    briefly described.

    Contacting MicroGenesis:
    Compuserve  : 76476,1701
    America On-Line : JeffH66
    InterNet  : [e-mail]
    Voice   : [phone]
    BBS   : [phone]


    Compiler Considerations:
     If you want to maximize portablilty between various computer platforms
    MultiApp can greatly speed this process.  However because even C/C++
    compilers interpret the C/C++ standard differently you must account for
    these differences in your code.  Thes
    e are generally only syntactical errors that will show up when you
    compile your application on another platform for the first time.

     MultiApp does not use pure c++ as its coding standard.  Pure C++ can
    defiantly be used with MultiApp but since many platforms(particularly
    the Macintosh) are lacking in the area of quality C++ compilers we have
    developed MultiApp based on a simpler
    subset of C++.  This is based on Symantec Think C 5's objects
    extension.  This is basically identical to C++ but without some of
    C++'s more complex features.  IF you want your application to be
    directly compilable on object based C compilers you shou
    ld not use the following C++ features:

     Function Overloading
     Operator Overloading
     Function Templates
     Parameters To Constructors
     Static Objects(ie MYOBJECT obj; is illegal it MUST be
        MYOBJECT *obj)
     this redefinition(this=this->next is illegal, all other standard this
    operations are legal however).
     All Functions MUST have prototypes.
     Cast all pointer conversions

     These are some general rules to follow to ensure that your programs
     are compatible with Object C type compilers as well as True C++
     compilers.  Once multiApp is ported into C++ compilers on both Dos and
     Mac these restrictions will not be necessary.
     We are currently working on creating a MPW version of MutliApp that
     will support full C++, but for now please remember that not all
     platforms have as "developed" of a base of C++ compilers as the IBM
     platform does.









     If you are going to be seriously developing cross-platform
    applications than it is suggested that you own a copy of BOTH
    Borland/Turbo C++ and Think C so you can see the differences for
    yourself.  I have not found it to be too much of a problem in o
    ur own development.  Just treat Think C as the "least common
    denominator" and you will do fine.  We will also be coming out with a
    document further describing Think C/Borland C++ compatibility with the
    release of MultiApp UI.


    Global Functions:
    void beep(void);
     This function will cause the users computer to beep.

    void c2pas(char *str);
     This function will transform str  into a pascal string(assuming it was
    originally a c string).

    void pas2c(char *str);
     This function will transform str  into a c string(assuming it was
    originally a pascal string).

    void sleep(int tenths);
     This function will wait for tenths 1/10ths of a second.

    int timer_check(long tm);
     Call this function,with the value timer_set returns, to see if the
    time is up.  If that time has elapsed then this function returns true.

    long timer_set(int tenths);
     Sets a timer for tenths 1/10ths of a second.  The value that this
    function returns should be passed to timer_check to determine if that
    time has elapsed.

    void timer_wait(long tm);
     Call this function with the value timer_set returns to wait until that
    amount of time elapses.

    void updcrc(unsigned char b);
     Each call of this function causes b to be calculated into the global
    crc.

    extern unsigned short crc;
     This variable is used with updcrc  to calculate a CRC value.  After
    you are done feeding updcrc your bytes, this is the variable you get
    your final CRC from.




    Definitions:

    The following are some general integer to binary conversion functions
    that allow MULTI-APP data to be compatible across platforms(especially
    since Intel and Motorola store ints exactly backwards of each other):
    #define HI_BYTE(x) (x/256)
    #define LO_BYTE(x) (x-(HI_BYTE(x)*256))
    #define BYTE_COMB(x,y) ((x*256)+y)








    CLASS NAME: ATOM       PARENT: NONE
    IMPORTANT CHILDREN: almost the whole library.

    Definition:

    class ATOM
    {
     public:
     ATOM();

     ATOM *next;// Next atom in a linked list
    };

    Description:

        The most fundamental class of MULTI-APP is the atom class.  Every
    object in the MULTI-APP library is derived from the atom class.  This
    allows general purpose "data container classes" to be defined for the
    atom.  These data container classes can
    then be used for other object types as well.  The most important of
    these data container classes is the linked list class(LIST). In its
    simplest form LIST allows a linked list of ATOM's,  but because WINDOW
    classes are derived from ATOM it is possibl
    e to create a linked list of WINDOWs or any other descendant of the
    ATOM class.

    Member Functions:
     ATOM();
      Description:
      CONSTRUCTOR - simply sets next equal to NULL.

      Returns:
      nothing

      See Also:

      Example:
       int search_for(ATOM *first,ATOM *lookfor)
        {
        // Search the linked list pointed to by "first" for
        // "lookfor".  Return TRUE if found

        while(first!=NULL)
         {
         if(first==lookfor)// Found it yet?
          return TRUE;
         first=first->next;// Next atom in list
         }
        }

    Data Members:
     ATOM *next;
      The next ATOM in the linked list.













    CLASS NAME: LIST       PARENT: ATOM
    IMPORTANT CHILDREN:  APP(from the user interface)
    Definition:

    class LIST:public ATOM
    {
     public:

     LIST(void);

     void add(ATOM *atom);
     void del(ATOM *atom);

     void first_element(void);
     void forward(void);
     void pos(long p);
     virtual int  comp(ATOM *a1,ATOM *a2);

     ATOM *first,*current;
    };

    Description:

     The LIST object is one of the primary classes of MULTI-APP.  LIST is a
    "data container object" designed to hold a linked list of ATOMS.
    Because almost every object in MULTI-APP is derived from ATOM, lists
    can be built of many different types of obj
    ects.  For example in the MULTI-APP User Interface section you will
    learn that the APP class is really a linked list of all open windows.
    Because APP is a child of LIST it can build lists of ANYTHING that is
    derived from ATOM.  This includes windows
    , dialogs and many other types of screen objects.

    Data Members:
     ATOM *first;
      This is the first ATOM in the linked list.  This gives LIST a
    starting point for list resets and searches.  If the list is empty then
    this variable contains a NULL.
     ATOM *current;
      Current is the atom that the list is currently processing.  It is
    perfectly legal for current to be NULL, even if the list has data in
    it.  A NULL current usually means  that you have reached the end of the
    list.


    Member Functions:

     LIST(void);
      Description:
      CONSTRUCTOR - This sets current and first to NULL, thus creating a
      new blank LIST.

      Returns:
      nothing

      See Also:
       ATOM









      Example:
       void main(void)
        {
        LIST *list;// The list we will be adding items to
        ATOMS *a,*b,*c; // Some atoms to add

        list=new LIST;
        list->add(a=new ATOM);
        list->add(b=new ATOM);
        list->add(b=new ATOM);

        // At this point the list would look something like:
        // a-->b-->c-->NULL

        list->del(b);

        // At this point the list would look something like:
        // a-->c-->NULL

        // Now loop through the list

        first_element();
        while(current!=NULL)
         forward();
        }

    _________________________________________________________
     void add(ATOM *atom);
      Description:
       atom - The atom being added to list.
      This function adds a new ATOM into the list.  The comp function is
    used to determine atom's position.  If comp  is not redefined then the
    atom is inserted at the end of the list.

      Returns:
      nothing

      See Also:
       del
       Example for LIST class.

      Example:
       void MYOBJECT::add(ATOM *atom)
        {// An add function for a derived LIST manager
        MYITEM *i=(MYITEM*)atom;

        // Now use "i" to officially add your type of object
        // This is usually some sort of inititilaztion

        LIST::add(atom);// Add it to the actual list
        }


    _________________________________________________________
     virtual int  comp(ATOM *a1,ATOM *a2);
      Description:
       a1 - The atom on the left side of the comparison
       a2 - The atom on the right side of the comparison









      This function compares a1  to a2  and returns:
      0   Both ATOMS are equal.
      >1  a1 is greater than a2
      <1  a2 is greater than a1
      Comp is used to sort ATOMS as they enter the list.

      Returns:
      nothing

      See Also:
       forward()
       Example for LIST class.

      Examples:

       // A compare function(the default) that will insert items into the
       list in reverse order.
       int class::comp(ATOM *a1,ATOM *a2){ return 1; }

       // A compare function that will insert items in the same order they
       are entered
       int class::comp(ATOM *a1,ATOM *a2){ return  -1; }

    _________________________________________________________
     void del(ATOM *atom);
      Description:
       atom - The atom being removed from the list.
      This function removes an ATOM from the list.  Please note that the
    memory for atom  is not freed, but rather the ATOM is simply pulled out
    of the list chain.
      Returns:
      nothing

      See Also:
       add
       Example for LIST class.

      Example:
       void MYOBJECT::del(ATOM *atom)
        {// An del function for a derived LIST manager
        MYITEM *i=(MYITEM*)atom;

        // Now use "i" to officially remove  your type of object
        // This is usually some sort of shutdown sequence

        LIST::del(atom);// Add it to the actual list
        }


    _________________________________________________________
     void first_element(void);
      Description:
      This function sets current  to first, thus moving the lists attention
      to its first element.  This function is usually called prior to a
      search.

      Returns:








      nothing

      See Also:
       forward()
       Example for LIST class.


    _________________________________________________________
     void forward(void);
      Description:
      This function moves the current pointer to the next ATOM in the list.
      If there are no more ATOMs or the list is empty then current is set
      to NULL.

      Returns:
      nothing

      See Also:
       first_element()
       Example for LIST class.
    _________________________________________________________
     void pos(long p);
      Description:
       p - element in list to move to.
      This function moves(points current to) the "p"th element in the
    linked list.
      Returns:
      nothing

      See Also:
       forward



































    CLASS NAME: DEVICE       PARENT: LIST
    IMPORTANT CHILDREN: FILEIO, and any device class made for MULTI-APP

    Definition:

    class DEVICE:public LIST
    {
     public:
     virtual int put(BYTE ch);
     virtual int putstr(char *str);
     virtual int goxy(int x,int y);
     virtual int inverse(void);
     virtual int normal(void);
     virtual BYTE get(BYTE *ch);
     virtual BYTE wait2get(BYTE *ch);
     virtual int hit(void);
     virtual int reset(void);
     virtual int ceol(void);
     virtual int wherex(void);
     virtual int wherey(void);
     virtual int printf(char *format,...);
     int getstr(char *str);
    };


    Description:
     DEVICE is a object that defines basic properties that any MULTI-APP
    compatible device should have.  DEVICE allows MULTI-APP to communicate
    to a device in a polled 8-bit manner.  Commands are provided to do
    basic byte I/O as well as some general cont
    rol commands that many "video" devices would have.  The commands
    provided here are the same on ALL the children of DEVICE.  So as a
    result the command to print a string is identical in all parts of
    MULTI-APP.



    Data Members:
     NONE

    Member Functions:
     virtual int ceol(void);
      Description:
      Ceol is only used in video devices, it will clear to the end of the
      line starting at wherex,wherey.

      Returns:
      nonzero on error.

      See Also:
       reset.


    _________________________________________________________
     int getstr(char *str);
      Description:
       str - the string read from the device.
      This function will input characters into the string str until a








    carriage return(#13) is received.  The final carriage return is not
    stored in the string. If the operation is successful this function will
    return a zero.

      Returns:
      nonzero on error.

      See Also:


    _________________________________________________________
     virtual BYTE get(BYTE *ch);
      Description:
       ch - if NULL does nothing, otherwise the BYTE read.
      This function receives the next 8-bit character from the device.  If
    none are available then this function returns a zero.  There are two
    paths by which this function returns its data.  First is through the
    normal function return, and second is via
     a pointer to a BYTE.  If you do not wish to use the pointer method
    simply call it as "get(NULL)".  Example: "x=get(NULL)", "get(&x)" and
    "x=get(&x)" all do exactly the same thing.

      Returns:
      character read, or a zero if none are available.

      See Also:
       put,getstr,wait2get,hit.

      Example:
       BYTE DEVICE::wait2get(BYTE *ch)
        {
        BYTE c;
        while(!hit());// Loop until something is available
        c=get(NULL);// Input character

        if(ch!=NULL)// Return by pointer if necessary
         *ch=c;

        return(c);
        }

    _________________________________________________________
     virtual int goxy(int x,int y);
      Description:
       x - The horizontal position to goto.
       y - The vertical position to goto.
      This function allows you to set the x and y coordinates of the
    device.  Not all devices have x/y coordinates, so this function is not
    used in all DEVICES.  If the operation is successful this function will
    return a zero.

      Returns:
       nonzero on error.

      See Also:
       reset.

      Example:








       void home(DEVICE *d)
        {// Home the cursor in any device(if it supports cursors)
        d->goxy(0,0);
        }

    _________________________________________________________
     virtual int hit(void);
      Description:
      Hit allows you to determine if there is a character waiting to be
      received(by one of the input functions).  Hit returns 0 if none are
      available. If data is waiting it returns the number of bytes waiting.

      Returns:
      true if there is a character waiting to be read.

      See Also:
       get,wait2get.

      Example:
       see get.



    _________________________________________________________
     virtual int inverse(void);
      Description:
      If the device is capable of having its foreground and background
      colors inverted this function inverses them.  If the operation is
      successful then this function will return a zero.   Inverse is left
      over from before MULTI-APP supported color, and i
    s rarely used anymore.

      Returns:
       nonzero on error.

      See Also:
       normal.

    _________________________________________________________
     virtual int normal(void);
      Description:
      This function resets any special modes(namely inverse) that may have
      been set on this device.  If the operation is successful this
      function will return a zero.

      Returns:
       nonzero on error.

      See Also:
       inverse.

    _________________________________________________________
     virtual int printf(char *format,...);
      Description:
       format - "stdio.h printf" format string to write.
      This output function allows you to output to a device in the classic
    C printf style.  Consult your C reference manual if you require
    additional information on printf.  Please note that the final outputted








    string cannot be larger than 199 characters
    , if it is the results are undefined.

      Returns:
      nonzero on error.

      See Also:
      put,putstr.

      Example:
       void main(void)
        {
        DEVICE *device;

        device=new DEVICE;
        device->goxy(10,10);// Move cursor

        device->printf("Cursor is at: %xi,%i.",// Display cursor's location
         device->wherex(),device->wherey());
        }




    _________________________________________________________
     virtual int put(BYTE ch);
      Description:
       ch - the character to be written.
      This function will attempt to write a single character to the device.
    If the operation is successful this function will return a zero.
      Returns:
       nonzero on error.

      See Also:
       putstr,printf.

      Example:
       void spc(DEVICE *device,int i)
        {// write out i spaces(32) to any type of device
        while(i--)
         d->put(32);
        }

    _________________________________________________________
     virtual int putstr(char *str);
      Description:
       str - the string to be written.
      This function repeatedly calls put  until a zero is reached in the
    string.    If the operation is successful this function will return a
    zero.

      Returns:
       nonzero on error.

      See Also:
       put,printf

      Example:








       int DEVICE::printf(char *format, ... )
        {// The printf function from DEVICE
        char string[200];
        va_list ptr;

        va_start(ptr,format);
        vsprintf(string,format,ptr);
        putstr(string);
        va_end(ptr);
        return 0;
        }

    _________________________________________________________
     virtual int reset(void);
      Description:
      Reset acts very different based on the device.  On most video devices
      it will clear the screen, while on others it flushes all I/O buffers.

      Returns:
      nonzero on error.

      See Also:
       goxy.




    _________________________________________________________
     virtual BYTE wait2get(BYTE *ch);
      Description:
       ch - if NULL does nothing, otherwise the BYTE read.
      This function enters a loop to wait for a character to be available
    then receives the next 8-bit character from the device.  There are two
    paths by which this function returns its data.  First is through the
    normal function return, and second is vi
    a a pointer to a BYTE.  If you do not wish to use the pointer method
    simply call it as "get(NULL)".  Example: "wait2get(NULL)",
    "wait2get(&x)" and "x=wait2get(&x)" all do exactly the same thing.
    WARNING:  This function can hang the system if no char
    acter ever becomes available.

      Returns:
       character read.

      See Also:
       put,getstr,hit.

      Example:
       see get.



    _________________________________________________________
     virtual int wherex(void);
      Description:
      The wherex function will return the x coordinate of this device.

      Returns:








      nonzero on error.

      See Also:
      wherey,reset,goxy.

      Example:
       void main(void)
        {
        DEVICE *device;

        device=new DEVICE;
        device->goxy(10,10);// Move cursor

        device->printf("Cursor is at: %xi,%i.",// Display cursor's location
         device->wherex(),device->wherey());
        }



    _________________________________________________________
     virtual int wherey(void);
      Description:
      The wherey function will return the y coordinate of this device.

      Returns:
      nonzero on error.

      See Also:
      wherex,reset,goxy.

      Example:
       void main(void)
        {
        DEVICE *device;

        device=new DEVICE;
        device->goxy(10,10);// Move cursor

        device->printf("Cursor is at: %xi,%i.",// Display cursor's location
         device->wherex(),device->wherey());
        }

























    CLASS NAME: COMIO       PARENT: DEVICE
    IMPORTANT CHILDREN: ALP

    Definition:
    class COMIO:public DEVICE
    {
        public:
     COMIO(void);
     ~COMIO();
     int init(int p);
     virtual int put(BYTE ch);
     virtual BYTE get(BYTE *ch);
     virtual int putstr(char *str);
     virtual int hit(void);
     virtual void baud(long r);
     virtual void disconnect(void);
     virtual int timed_get(BYTE *ch,int secs);

     void flush_out(void);
     void flush_in(void);
     void purge_out(void);
     void purge_out(void);
     void flow(int i);

     void dtr(int i);
     char carrier(void);

     int direct,no_modem;
     long lockbaud;
     long baudrate,bps;
        private:
     Varies with operating system.
    };

    Description:
     COMIO provides a platform-independent method for communicating with
    the computer's serial ports. COMIO follows the strict interface
    definition defined by the DEVICE class, and is consistent with all
    other MULTI-APP classes in that way.  You can spec
    ify many additional arguments that are compatible only with a serial
    device, yet all serial I/O is compatible with the DEVICE class.
    Hardware comport numbers always start at 1.

    Data Members:
      long baudrate
       The baud rate that the remote modem is at, regardless of locked
    baudrate.  This must be maintained by the user if it is needed.

      long bps
       The port's baud rate, if baud rate is locked then this should never
    be different than lockbaud.  This value is set internally by MultiApp
    and is meant for reference only.

      char detect_carrier
       If this value is true then the carrier function returns the status
    of the carrier pin.  If this value is false then carrier always returns
    true.









      int direct
       If this value is one then the COMIO object will do all of its
    communication at the most direct level possible.  On Mac this would be
    through the serial manager, on Dos this would mean through interrupts
    and ports.  If this value is zero then the C
    OMIO object will do all of its communication at a higher level. On Mac
    this would still be through the serial manager, on dos this would be
    through BIOS or a FOSSIL if one is loaded.   Generally you should set
    this as 1.   WARNING: never change this
    value once init has been called.


      long lockbaud
       This variable allows you to lock the baud rate at some speed.  If
    you set it to zero(the default) then baud rate is variable.  Some 9600
    baud modems require their baud rate to be locked at 38,400 baud, this
    function makes the use of such modems ea
    sier.


      int no_modem
       If this variable is set to one then no communication with the serial
    ports is made.  This provides for a sort of test mode.


      port
       Serial port number that this instance of COMIO is working with.





    Member Functions:
     COMIO(void);
      Description:
      CONSTRUCTOR - Allocates any memory needed for buffers.

      Returns:
      nothing.

      See Also:
      ~COMIO.

      Example:
      // VTERM is a simple tty terminal that must be provided with a DEVICE
      to use
      // as a console.  This console is usually something such as the UI's
      CONIO object
      // however it can really be anything, even another COMIO(which would
      provide a
      // remote terminal.  Press \ for a list of commands in this terminal.
      void vterm(DEVICE *con,COMIO *com)
      {
      // con - console device
      // com - "modem" interface
      int done=0;
      char ch;// Check for commands









       com->baud(2400);// Default to 2400 baud

       while(!done)
        {
        if(con->hit())// Output keypress
         {
         ch=con->get(NULL);
         if(ch!='\')
          com->put(con->get(NULL));
         }

        if(com->hit())// Display incoming data
         con->put(com->get(NULL));

        if(ch=='\')
         {
         char str[100];
         con->reset();
         con->putstr("Select an option: <B>aud <D>isconnect or <Q>uit? ");
         switch( toupper(con->wait2get(NULL)))
          {
          case Q':done=1;break;
          case D':com->disconnect();break;
          case B':con->putstr("\rWhat baud? ");
           con->getstr(str);
           con->baud(atoi(str));
           break;
          }
         }
        }
      }


    _________________________________________________________
     ~COMIO();
      Description:
      DESTRUCTOR - Releases any allocated memory, and closes the hardware
      serial port.

      Returns:
      nothing.

      See Also:
      COMIO.

    _________________________________________________________
     virtual void baud(long r);
      Description:
       r - The baud rate that you wish to use.
      Commands the hardware comport to do all I/O at r  baud rate.

      Returns:
      nonzero on error.

      See Also:
      init.

      Example:








       see constructor example.

    _________________________________________________________
     virtual void baud(long r);
      Description:
       r - The baud rate that you wish to use.
      Commands the hardware comport to do all I/O at r  baud rate.

      Returns:
      nonzero on error.

      See Also:
      init.

      Example:
       see constructor example.

    _________________________________________________________
     virtual void disconnect(void);
      Description:
      This function is intended for when the serial port is connected to a
      hayes compatible modem.  Disconnect attempts to break the connection
      by dropping DTR, if that doesn't work then the classic +++ followed
      by ATH is sent.

      Returns:
      nonzero on error.

      See Also:
      dtr.

      Example:
       see constructor example.


    _________________________________________________________
     void dtr(int i);
      Description:
       i - State of DTR:1=on, 0=off.
      This function allows you to set the state of the DTR line.  Call it
    with 1 to raise DTR, zero to lower DTR.

      Returns:
      nothing.

      See Also:

      Example:
       void COMIO::disconnect()
        {
        int i;

        dtr(0);// Attempt to disconnect using DTR
        sleep(30);
        dtr(1)

        if(!carrier())// If no carrier then we are done
         return;









        for(i=0;i<=2;i++)
         {
         COMIO::put('+');
         sleep(30);
         }
        sleep(15);
        COMIO::putstr("\rATH0\r");
        }


    _________________________________________________________
     void flush_in(void);
      Description:
      This function will clear out the current inbound buffer, and any
      characters that may arrive while clearing.  It will not return until
      the hit function returns a zero.
      Returns:
      nothing
      See Also:
      flush_out,purge_in,purge_out

    _________________________________________________________
     void flush_out(void);
      Description:
       This functions for the operating system to transmit any characters
    waiting in the out buffer.

      Returns:
      nothing.

      See Also:
      flush_in,purge_in,purge_out



    _________________________________________________________
     virtual BYTE get(BYTE *ch);
      Description:
       ch - Pointer to where to store read character(if not NULL).
      This function receives the next 8-bit character from the serial port.
    If none are available then this function returns a zero.  There are two
    paths by which this function returns its data.  First is through the
    normal function return, and second i
    s via a pointer to a BYTE.  If you do not wish to use the pointer
    method simply call it as "get(NULL)".  Example: "x=get(NULL)",
    "get(&x)" and "x=get(&x)" all do exactly the same thing.

      Returns:
      character read.

      See Also:
      put,getstr,hit.

      Example:
       see constructor example.

     _________________________________________________________








     virtual int hit(void);
      Description:
      Hit allows you to determine if there is a character waiting to be
      received(by one of the input functions).  Hit returns 0 if none
      available. If data is waiting it returns the number of bytes waiting.

      Returns:
      true if there is a character available.

      See Also:
       get,wait2get.

      Example:
       see constructor example.



    _________________________________________________________
     int init(int p);
      Description:
       p - the comport that you want to use.
      Opens hardware comport p and attaches it to this object.

      Returns:
      nonzero on error.

      See Also:
      ~COMIO.

      Example:
       see constructor example.
    _________________________________________________________
     void purge_in(void);
      Description:
      This function will erase any characters that are currently in the
      input buffer.
      Returns:
      nothing
      See Also:
      flush_in,flush_out,purge_out

    _________________________________________________________
     void purge_out(void);
      Description:
       This function removes any characters from the output buffer, causing
    them to never be transmitted.

      Returns:
      nothing.

      See Also:
      flush_out,flush_in,purge_in




    _________________________________________________________
     virtual int put(BYTE ch);








      Description:
       ch - the character to be written.
      This function will attempt to write a single character to the device.
    If the operation is successful this function will return a zero.

      Returns:
      nonzero on error.

      See Also:
      get,putstr,printf.

      Example:
       see constructor example.


    _________________________________________________________
     int putstr(char *str);
      Description:
       str - the string or modem command.
      This function is used primarily for modem commands.  If the string
    starts with the letters AT then the string is assumed to be a modem
    command and some extra processing is done.  Otherwise the string is
    simply written to the serial port.  Modem str
    ings may have the following characters imbedded in them:

     | (pipe) = carriage return
     {  = carriage return
     v(lowercase)= drop dtr
     ^(carrot) = raise dtr

      Returns:
      zero on success.

      See Also:


    _________________________________________________________
     virtual int timed_get(BYTE *ch,int secs);
      Description:
       ch - pointer to where to store read character.
       secs-how many tenths of a second to wait for the character.
      This function receives the next 8-bit character from the serial port.
    If none are available then this waits secs 1/10ths of a seconds for one
    to arrive.  If a character was found before timeout this function
    returns 0, otherwise a one is returned.
      The actual character is returned by the ch pointer.

      Returns:
      nonzero on error.

      See Also:















    CLASS NAME: ALP       PARENT: COMIO
    IMPORTANT CHILDREN: none

    Definition:
    struct ALP:public COMIO
    {
    public:
     ALP();
     void update(void);// Call this as often as possible
     void intr(void);
     int check(void);  // Check for ALP-compat device on remote side
     void transmit(void); // transmit a packet

     // Replacements for CONIO functions:
     virtual int put(BYTE ch);
     virtual BYTE get(BYTE *ch);
     virtual int hit(void);
     virtual void disconnect();

     char str[2000];
     int p;
     BYTE intrans;
     BYTE no_alp;

    private:
     // Incoming queue
     void push(BYTE ch);
     BYTE pop(void);

     void input(BYTE ch);

     BYTE hi,lo;
     BYTE in_packet[2048];
     BYTE uncomp[2048];
     BYTE phase;
     int in_length;
     int in_num;
     unsigned short in_crc;
     unsigned short in_tcrc;
     int in_loc;

     BYTE queue[ALP_IN];
     int front,back;

     int background;
     BYTE outnum;
     BYTE lastnum;
    };


    Description:
     ALP(Anti Line noise Protocol) is a replacement for COMIO that ensures
    a 2-way reliable serial connection.  Data is sent out in packets(which
    are compressed using the LZSS protocol) that are verified to insure a
    reliable link.  It is 100% compatible
    with the COMIO object.  This communications standard allows separate
    MULTI-APP applications to have a common hi-level method of
    communication.  When using ALP you can use put,get and all the other








    COMIO functions and let ALP worry about the error che
    cking.  Except for the update function none of the additional contents
    of this class are of any real use to the application programmer.


    Data Members:
     BYTE intrans;
      Intrans is a flag that tells if a packet is in transit or not.  If a
    packet is in-transit it means that the packet has been sent, yet ALP is
    unsure if it made it through correctly or not.  Intrans holds 1 if
    block is in transit, zero if not.

     BYTE no_alp;
      no_alp is a flag that tells if ALP is enabled or not.  If ALP is
    disabled then all calls are passed directly through to the COMIO
    object.

     int p;
      P tells ALP how many characters are in the str  buffer waiting to go
    out in the next packet.  See str  for more details.

     char str[2000];
      This is the buffer where outgoing data is held until it is packeted.
    This variable is made public because it is perfectly legal to memcopy
    stuff into str and modify p  directly.  This is particularly appealing
    in file transfer situation as it cuts
     the overhead induced by the COMIO replacements.





    Member Functions:
     ALP();
      Description:
      CONSTRUCTOR - The ALP constructor sets up all buffers and initialized
      all pointers.

      Returns:
      nothing.

      See Also:

      Example:
      // VTERM-ALP is a simple tty terminal that must be provided with a
      DEVICE to use
      // as a console.  This console is usually something such as the UI's
      CONIO object
      // however it can really be anything, even another COMIO(which would
      provide a
      // remote terminal.  Press \ for a list of commands in this terminal.
      // This example is very similar to the example given in COMIO, this
      shows how
      // compatible these two classes are.
      void vterm(DEVICE *con,ALP *com)
      {
      // con - console device
      // com - "modem" interface








      int done=0;
      char ch;// Check for commands

       com->baud(2400);// Default to 2400 baud

       while(!done)
        {
        com->update();// For ALP to packet everything when needed

        if(con->hit())// Output keypress
         {
         ch=con->get(NULL);
         if(ch!='\')
          com->put(con->get(NULL));
         }

        if(com->hit())// Display incoming data
         con->put(com->get(NULL));

        if(ch=='\')
         {
         char str[100];
         con->reset();
         con->putstr("Select an option: <B>aud <D>isconnect,<A>lp  or
         <Q>uit? ");
         switch( toupper(con->wait2get(NULL)))
          {
          case Q':done=1;break;
          case D':com->disconnect();break;
          case B':con->putstr("\rWhat baud? ");
           con->getstr(str);
           con->baud(atoi(str));
           break;
          case A':
           if(com->check())
            con->putstr("ALP active\r");
           break;
          }
         }
        }
      }

    _________________________________________________________
     int check(void);
      Description:
      This function is used to establish an ALP session.  Check transmits
      the ALP init string and waits for a reply.  If the other side
      replies(it does this automatically via update) then both sides no_alp
      values gets set to zero and an ALP session begi
    ns.

      Returns:
      TRUE if ALP link has been established.

      See Also:
      update,intr.

      Example:








       see constructor example.


    _________________________________________________________
     virtual void disconnect(void);
      Description:
      This function is intended for when the serial port is connected to a
      hayes compatible modem.  Disconnect first ends the ALP session.  Then
      disconnect attempts to break the connection by dropping DTR, if that
      doesn't work then the classic +++ follow
    ed by ATH is sent.

     Returns:
      nothing.

     See Also:
      dtr.

     Example:
       see constructor example.

    _________________________________________________________
     void dtr(int i);
      Description:
       i - State of DTR:1=on, 0=off.
      This function allows you to set the state of the DTR line.  Call it
    with 1 to raise DTR, zero to lower DTR.

      Returns:
      nothing.

      See Also:

      Example:
       void COMIO::disconnect()
        {
        int i;

        dtr(0);// Attempt to disconnect using DTR
        sleep(30);
        dtr(1)

        if(!carrier())// If no carrier then we are done
         return;

        for(i=0;i<=2;i++)
         {
         COMIO::put('+');
         sleep(30);
         }
        sleep(15);
        COMIO::putstr("\rATH0\r");
        }

    _________________________________________________________
     void flow(int i);
      Description:
       i - flow control type:








        0 = NONE
        1 = CTS/RTS(hardware)
        2 = XON/XOFF(software)
        3 = both hardware and software

      This function sets the flow control mode of the serial port.  This is
    useful for high speed modems.

      Returns:
      nothing.

      See Also:
    _________________________________________________________
     virtual BYTE get(BYTE *ch);
      Description:
       ch - Pointer to where to store read character(if not NULL).
      This function receives the next 8-bit character from the ALP driver.
    If none are available then this function returns a zero.  There are two
    paths by which this function returns its data.  First is through the
    normal function return, and second is
     via a pointer to a BYTE.  If you do not wish to use the pointer method
    simply call it as "get(NULL)".  Example: "x=get(NULL)", "get(&x)" and
    "x=get(&x)" all do exactly the same thing.

      Returns:
      the character read.

      See Also:
      getstr,put,hit.

      Example:
       see constructor example.

    _________________________________________________________
     virtual int hit(void);
      Description:
      Hit allows you to determine if there is a character waiting to be
      received(by one of the input functions).  Hit returns 0 if none
      available. If data is waiting it returns the number of bytes waiting.

      Returns:
      the number of characters waiting to be read.

      See Also:
       get.

      Example:
       see constructor example.



    _________________________________________________________
     void intr(void);
      Description:
      Intr is similar to update, except that it is intended to be called
      from an interrupt if that is how you desire to make sure ALP stays
      updated.









      Returns:
      nothing.

      See Also:
       update.

    _________________________________________________________
     virtual int put(BYTE ch);
      Description:
       ch - character to be written.
      This function will attempt to write a single character to the device.
    If the operation is successful this function will return a zero.

      Returns:
      nonzero on error.

      See Also:
       printf,putstr.

      Example:
       see constructor example.

    _________________________________________________________
     void transmit(void);
      Description:
      Transmit will force a packet to be transmitted.

      Returns:
      nothing.

      See Also:


    _________________________________________________________
     void update(void);
      Description:
      Update should be called as often as possible, as it checks the
      incoming data line for packets and transmits any waiting data in a
      packet.

      Returns:
      nothing.
      See Also:
       intr.

      Example:
       see constructor example.



















    CLASS NAME: FILEIO       PARENT: DEVICE
    IMPORTANT CHILDREN: none

    Definition:

    class FILEIO:public DEVICE
     {
     public:
     FILEIO();
     ~FILEIO();
     int gethandle(void);

     void open_file(char *path,char *name,char md,char *type,char
    *creator);

     void fread(void *loc,long len);
     void fwrite(void *loc,long len);
     char end(void);
     char error(void);
     void close_file(void);
     void pos(long loc);
     long where(void);

     virtual int put(BYTE ch);
     virtual BYTE get(BYTE *ch);
     char sharing;
     char filename[80];
     };



    Description:
     FILEIO provides a platform-independent method for accessing files.  It
    is setup exactly like any other MGBBS DEVICE.  Support is provided for
    file sharing(in platforms that support it).  All single character
    commands are buffered to provide maximum
    speed.



    Data Members:
     char sharing;
      Holds 1 if file sharing is on, 0 if it is off(set by user).
     char filename[80];
      Holds the full file name(including path).

    Member Functions:
     FILEIO();
      Description:
      CONSTRUCTOR - sets up all pointers, handles etc.

      Returns:
      nonzero on error.

      See Also:

      Example:
       int copyfile(char *source_path,char *source_name,char








    *dest_path,char *dest_name)
       {// This function will copy a file.  Please note that this function
    will only copy the
       // data fork of a Macintosh File.
       FILE *in,*out;

       in=new FILEIO;
       out=new FILEIO;

       in->open_file(source_path,source_name,'r',"","");
       out->open_file(dest_path,dest_name,'w',"","");

       if(in->error() || out->error() )
        {
        delete in;// Delete both file objects(this will close either if
        they were opened)
        delete out;
        return 1;// return an error condition
        }

       while(!in->end())// Loop until end-of-file is reached
        out->put(in->get(NULL));

       in->close_file();
       out->close_file();
       }


    _________________________________________________________
     ~FILEIO();
      Description:
      DESTRUCTOR - closes file if open.

      Returns:
      nonzero on error.

      See Also:

    _________________________________________________________
     void close_file(void);
      Description:
      This function will close the file, allowing the same data structure
      to be used for another file.

      Returns:
      nonzero on error.

      See Also:



    _________________________________________________________
     char end(void);
      Description:
      This function returns true if the end of the file has been reached.

      Returns:
      nonzero on error.









      See Also:


    _________________________________________________________
     char error(void);
      Description:
      This function returns true if the file is in an error condition.

      Returns:
      nonzero on error.

      See Also:

    _________________________________________________________
    void fwrite(void *loc,long len);
      Description:
       loc - The location in memory your writing from.
       len - The length of the block being written.
      This function, which is similar to the <stdio.h> function of the same
    name, allows you to write something pointed to by loc  of length len to
    the file.

      Returns:
      nonzero on error.

      See Also:


    _________________________________________________________
     void fread(void *loc,long len);
      Description:
       loc - Pointer to the location in memory to hold block
       len - The length of the file you wish to read.
      This function, which is similar to the <stdio.h> function of the same
    name, allows you to read something into an area pointed to by loc  of
    length len  from the file.

      Returns:
      nonzero on error.

      See Also:


    _________________________________________________________
     virtual BYTE get(BYTE *ch);
      Description:
       ch - Pointer to where to store read character(if not NULL).
      This function receives the next 8-bit character from the device.  If
    none are available then this function returns a zero.  There are two
    paths by which this function returns its data.  First is through the
    normal function return, and second is via
     a pointer to a BYTE.  If you do not wish to use the pointer method
    simply call it as "get(NULL)".  Example: "x=get(NULL)", "get(&x)" and
    "x=get(&x)" all do exactly the same thing.

      Returns:
      nonzero on error.









      See Also:



    _________________________________________________________
     int gethandle(void);
      Description:
      Most operating systems use a single integer to reference a file. If
      the operations system your using MULTI-APP in supports such file
      referencing this function returns that value.  Use of this function
      should be avoided, as it can cause code created
     for MULTI-APP to be incompatible on other platforms.

      Returns:
      nonzero on error.

      See Also:


    _________________________________________________________
     void open_file(char *path,char *name,char md,char *type,char
    *creator);
      Description:
       path - The location in the file system of the file.
       name - The actual name of the file.
       md - The access mode your using for the file.
       type - The 4 character file type(only used on some OS's)
       mode - The 4 character file signature(only used on some OS's)
      This function is used to tell FILEIO which fill it will be accessing.
    You can specify both a path and a name.  md should be one of the
    following:
      r' for reading(other users are allowed to also read)
      w' for writing and truncation(other users must wait to access file)
      +' both read and write(other users must wait to access file)
      s' for both read/write(other uses may have full access to file)
      a' for appended write(other users must wait to access file)
      The type and creator allow you to specify these fields if your
      operating system supports them.  The w' command will erase anything
      that was in the file beforehand.  If you wish to write a single
      record in a file you must open with the +' command, e
    ven if you will not be reading.

      Returns:
      nonzero on error.

      See Also:



    _________________________________________________________
     void pos(long loc);
      Description:
       loc - Location in bytes to place file pointer.
      This function will position the file position at loc.

      Returns:
      nonzero on error.









      See Also:

    _________________________________________________________
     virtual int put(BYTE ch);
      Description:
       ch - The character to be written to the file.
      This function will attempt to write a single character to the device.
    If the operation is successful this function will return a zero.

      Returns:
      nonzero on error.

      See Also:

    _________________________________________________________
     long where(void);
      Description:
      This function will return the current file position.

      Returns:
      nonzero on error.

      See Also:










































    CLASS NAME: STACK      PARENT: NONE
    IMPORTANT CHILDREN: NONE

    Definition:
    class STACK
    {
    public:
     STACK();
     int pop(void);
     void push(int v);
     int empty(void);

    private:
     int location;
     int stack[STACK_SIZE];
    };


    Description:
     Stack sets up a stack(FIFO) to hold integers.  This stack may be upto
    STACK_SIZE in length.


    Data Members:
     NONE

    Member Functions:
     STACK();
      CONSTRUCTOR - sets up a empty stack.

     int pop(void);
      Pops an integer from the stack.

     void push(int v);
      Pushes an integer onto the stack.

     int empty(void);
      This function allows you to tell if a stack is empty.  It returns
    nonzero if the stack has items, zero if there are none.



























    Glossary
    BAUD - the communication rate between two devices. Baud rates usually
    range from 300 to 38400 baud.
    CARRIER - is a signal generated by a remote modem to say that it is
    still on-line.  In any serious communications program carrier must be
    repeatedly checked to ensure the remote modem is still connected.
    CREATOR - a file ID used by some operating systems(most notably the
    Mac) that allows data files to know "who created them."
    DATA CONTAINER - A dynamic holding area for data that can shrink or
    grow to handle the amount of data sent.  Data containers usually store
    data in some predetermined way.
    DTR - The software on/off switch for a modem.  If DTR is lowered the
    modem hangs up and will not accept any commands until the DTR is
    raised.
    DYNAMIC - Able to change to meet the situation at hand.  Dynamic
    containers only take up the amount of memory needed.
    FALSE - A value is said to be false when it contains a zero.
    FIFO - "First In First Out" a way of describing how a data container
    works, usually associated with a queue.
    FILE TYPE - some operating systems(most notably the Mac) allow you to
    assign a file type to any file you open.
    HAYES COMPAT - A type of modem that understands the hayes AT style
    command.  A hayes modem receives all its commands over the data lines,
    rather than the special control lines.
    INTERRUPT - When the computer stops doing what it was doing to handle
    something that has happened.
    INTERRUPT DEVICE - A device that stops the computers processing to
    handle its changed state.
    LINE NOISE - Errors that commonly occur in data communication caused by
    bad phone lines.
    LIFO - "Last In First Out" a way of describing how a data container
    works, usually associated with a stack.
    LINKED LIST - A sort of dynamic array.  A linked list holds a series of
    elements in some predetermined order.
    MODAL-A window that once on your screen is the only thing that you can
    access until it is "dismissed."
    MODELESS-A window that can be moved to the background by clicking
    another window on the screen.
    POLLED DEVICE - A device that generates no interrupt when its state
    changes, but rather must be polled to determine if it is ready.  All
    devices in MULTI-APP are polled.
    QUEUE - A data container commonly put between to devices of differing
    speeds.  A queue will accept information and release it in the same
    order as it got it.  Think of a queue as a one-way street, only one
    entrance and only one exit.
    STACK - A data container commonly used when you want to leave something
    the same way you came.  A stack will accept information and release the
    last item you entered, then the 2nd to last and so on.  Think of a
    stack as a restaurant plate holder, you
     can only get the plate on the top.  If you want to get the bottom
    plate you must remove all plates.
    TRUE - A value is said to be true when it holds any value other than
    zero.